4.9.4 查询单个终端信息

基本信息

Path： /api/v1/device/query

Method： GET

接口描述：

查询终端详细信息。
可以基于 externalId 或 mac 地址查询终端详细信息，不允许同时传入 externalId 和 mac，否则报错。
基于 mac 查询终端详情时，如果匹配到多条数据，则报错。
接口适用于 v2.2.9 及以上版本。

请求参数

根据 externalId 查询

参数名称	是否必须	示例	备注
externalId	必须	0c4e9039-f81d-11ec-a760-fefcfe545bb7	外部 ID

请求示例

/api/v1/device/query?externalId=0c4e9039-f81d-11ec-a760-fefcfe545bb7

根据 mac 查询

参数名称	是否必须	示例	备注
mac	必须	FE-FC-FE-21-F5-D1	mac 地址

请求示例

/api/v1/device/query?mac=FE-FC-FE-21-F5-D1

返回数据

名称	类型	是否必须	备注	其他信息
code	number	必须	返回码，0 返回成功
data	object	必须	报文数据主体
├─ externalId	string	必须	外部 ID
├─ macList	string[]	非必须	MAC 地址列表
├─ deviceName	string	必须	终端名称
├─ deviceType	string	必须	设备类型：'PC' PC 端，'Mobile' 移动端
├─ assetType	string	必须	资产类型：'CYOD' 企业终端，'BYOD' 个人终端，'COPE' 企业纳管个人终端，'NONE' 未定义
├─ tagList	string[]	非必须	标签列表
├─ deviceBrand	string	必须	品牌
├─ os	string	必须	操作系统
├─ windowsDomain	string	必须	windows 域控	终端加入的域
├─ broswer	string	必须	最后接入方式
├─ clientVersion	string	必须	客户端版本	>=2.2.10 SP3 开始支持(2.2.12 除外)
├─ lastNetworkZone	string	必须	最后接入网络区域
├─ lastLoginTime	string	必须	最后接入时间
├─ lastActiveTime	string	必须	终端最后活跃时间
├─ idleTime	number	必须	终端闲置时长（单位：天）
├─ onlineStatus	number	必须	在线状态：0 离线 1 在线
├─ loginStatus	number	必须	接入状态：0 未接入 1 已接入
├─ trusted	number	必须	终端授信状态:0 未授信 1 已授信
├─ firstImportTime	string	必须	首次录入时间
├─ lastLoginUser	string	必须	最后登录用户名
├─ displayName	string	必须	最后登录用户显示名
├─ userDescription	string	必须	最后登录用户描述
├─ userDirectoryName	string	必须	最后登录用户所属目录
├─ path	string	必须	最后登录用户所属组织架构
├─ bindUsers	object[]	非必须	绑定用户信息
├─├─ bindUser	string	非必须	用户名
├─├─ bindType	string	非必须	绑定方式：'userSelfBind' 自助绑定，'adminBind' 管理员绑定, 'adminAdmit' 管理员审批
├─├─ bindTime	string	非必须	绑定时间
├─ historyUsers	object[]	非必须	历史登录用户
├─├─ userName	string	非必须	用户名
├─├─ displayName	string	非必须	用户显示名
├─├─ userDescription	string	非必须	用户描述
├─├─ userDirectoryName	string	非必须	用户所属目录名
msg	string	必须	返回提示信息，与返回码对应
traceId	string	必须	调用链 ID，链路请求的标识

返回示例

{
  "code": 0,
  "data": {
    "externalId": "0c4e9039-f81d-11ec-a760-fefcfe545bb7",
    "macList": ["FE-FC-FE-21-F5-D1", "FE-FC-FE-21-F5-D2"],
    "deviceName": "DESKTOP-SDKLASKQ",
    "deviceType": "PC",
    "assetType": "CYOD",
    "tagList": ["开发测试终端", "办公网终端"],
    "trusted": 1,
    "bindUsers": [
      {
        "bindUser": "张三",
        "bindType": "adminBind",
        "bindTime": "2022-06-15 18:35:28"
      },
      {
        "bindUser": "李四",
        "bindType": "adminAdmit",
        "bindTime": "2022-06-15 18:35:28"
      }
    ],
    "historyUsers": [
      {
        "userName": "user1",
        "userDirectoryName": "本地用户目录",
        "displayName": "",
        "userDescription": ""
      },
      {
        "userName": "t1",
        "userDirectoryName": "本地用户目录",
        "displayName": "",
        "userDescription": ""
      }
    ],
    "deviceBrand": "SANGFOR",
    "os": "windows 10",
    "windowsDomain": "ADDOMAIN1",
    "lastLoginUser": "张三",
    "displayName": "张三三",
    "userDescription": "这是一名本地用户",
    "userDirectoryName": "本地用户目录",
    "path": "/",
    "lastLoginMethod": "Edge/98.0.1108.50",
    "clientVersion": "2.2.10.2",
    "lastLoginNetZone": "内网IP",
    "lastLoginTime": "2022-06-27 14:22:09",
    "lastActiveTime": "2022-06-27 14:26:02",
    "idleTime": 2,
    "onlineStatus": 1,
    "loginStatus": 1,
    "firstImportTime": "2022-06-24 15:20:26"
  },
  "msg": "请求成功",
  "traceId": "0022c672e4c8b0d6"
}

错误信息

错误提示	错误码
MAC 地址格式错误	7201
外部 ID 中不能含有非法的特殊字符：换行符，制表符，回车符	7201
外部 ID 长度超过最大上限：%d	7201
请输入匹配参数	10000001
请勿输入多个匹配参数: %s	10000001
终端不存在	77200001
匹配到多条终端，请求失败	37400404

4.9.4 查询单个终端信息

4.9.4 查询单个终端信息

results matching ""

No results matching ""